Loading and running the demonstration software.

* Under DOS, type VS48 for a 48K system or type VS32 for a 32K 
system. This is the text to speech driver. It loads in high 
memory and protects itself. NEWDOS+ ver. 2.1 users must set 
memory to 60666 for VS48 or 44277 for VS32.

* Load BASIC (the memory size is already set), and from the 
READY prompt type RUN"VSDEMO/BAS". You should hear a short 
introductory message, then you can try out the various 
capabilities of the system. Follow the instructions in the 
program. Type 1 to try the text to speech demonstration, then 
you can type any message you want and press the enter key to 
hear it. Press the enter key again to hear the message again.

Text to speech hints

The text to speech success rate is better than 90%. By using 
the following methods, you will be able to get a perfect score.

* Misspell the word. If the word comes out wrong, try spelling 
it phonetically. For example, the word "read" will be 
pronounced like "reed", even if you want it to sound like 
"red". If you want it to sound like "red", spell it red".

* To say initials, such as TRS-80 or IBM, simply put a space 
between the letters (that is T R S 80 or I B M). For a more 
natural sound, insert dashes instead of spaces between letters.  
Each space adds a pause. Dashes separate words or letters for 
pronunciation but do not add a pause. Try T-R-S-80. Also 
compare "thank you" with "thank-you".

* Spaces, periods, commas, and exclamation points add pauses. 
Other punctuation like " ;:?() do not. They are treated as 
"word separators" for pronunciation rules.

* Any number up to ninety nine trillion will be spoken 
correctly. (You can use commas and decimals) Example: 
12,345,000.67

* For ordinal numbers add the proper ending, i.e. 1st, 2nd, 
3rd, 4th, . 2,345th, etc.

* Some abbreviations are supported: Mr., Mrs., Ms., Co., lb., 
oz., ft., Dr., etc.

* The following punctuation symbols are pronounced: #, $, %, &, 
@, *, =, +, -

* Frequently, you will use the "-" (dash or minus sign) to link 
and split words to improve pronunciation. Use "-" if you mean 
"minus". Example: 49--43=6

* The VS32 and V548 programs accept 255 character strings as 
input. Generally, this will mean roughly 255 phonemes (about 25 
seconds of speech) if you type only words. If you use numbers, 
abbreviations or symbols, you may create very long phoneme 
lists.  If the resulting phoneme list is larger than 300 
phonemes, it will overwrite some of the rules.  This is not a 
problem as messages in practice will rarely exceed 10-15 
seconds.

* The VSEDIT program will accept up to 175 phonemes per 
message.  Excess phonemes will be spoken the first time you hit 
enter, and then they will be lost.

Adding speech to your programs

There are four methods to generate speech with your VS-100. 
These methods evolved as we developed the system. We will 
describe each below, starting with the latest development.

METHOD 1: PRINT* (pronounced "print star") PRINT*"something 
that will be said" This is a new BASIC command. BASIC will 
recognize the PRINT*"any string" statement and say the string. 
In order to do so, you must:

* From DOS type VS48 for 48K systems (and press ENTER) or type 
VS32 for 32K systems This loads the text to speech program in 
high memory and protects itself, (except NEWDOS+ ver. 2.1). 
VS48 resides from 60662 to 65535, VS32 resides from 44278 to 
49151 IMPORTANT: If you have a 48K system and you need the high 
memory, (For example: LDOS uses high memory for drivers) you 
can use VS32.

* You must also add the following POKEs to your program: (It 
need only be executed once and it will remain intact until you 
exit from BASIC) 

* For 48K systems:
5 PEEK(16844)<>237 THEN POKE -4852, PEEK(16843):POKE -4851, 
PEEK(16844) : POKE 16843,9 : POKE 16844,237

* For 32K systems:
6 IF PEEK(16844)<>173 THEN POKE -21236, PEEK(16843) : POKE 
-21235, PEEK(16844) : POKE 16843,9 : POKE 16644,173

If you really want to know, these pokes detour the DOS exit in 
ROM that checks for PRINT# to disk.

For your convenience, these lines are supplied on your disk 
saved in ASCII format (the file name is PRTSTAR/TXT). To avoid 
typing error and save time, you can MERGE"PRTSTAR/TXT" to your 
program. Make sure your program doesn't already use line 
numbers 5 or 6. IMPORTANT: only one of the lines should be in 
your program

* 48K systems: delete line 6 (keep line 5)

* 32K systems: delete line 5 (keep line 6)

NOTE: This line can be renumbered anywhere, provided it is 
executed once prior to using 

PRINT*.

The following are examples of speech output commands that 
become valid:

PRINT* "Hello"
PRINT* A$
PRINT* LEFT$(B$,3)
PRINT* "My name is "+A$ 

Like the PRINT command, PRINT* can be abbreviated ?*. In 
addition, any valid string expression can be used with PRINT* 
and ?*.

NOTE 1: In some cases, PRINT* will cause a line feed on your 
screen. To avoid this, simply add a semicolon (;) at the end of 
your PRINT* statement. Example: PRINT* A$+B$;

**NOTE 2: PRINT* is set to use pitch 2 only.

Here are some more elaborate examples:
?* STRING$(34,"E")      long EEEE sound like a buzzer
?* MID$(TIME$,10,5)     the current time
?* STR$(X)      say value of variable X

PRINT* can be used only with strings. Numeric expressions must 
be converted to strings using the BASIC STR$ function.

PRINT* is the easiest way to generate speech with your VS-100.

*METHOD 2: USR call

You can use the VS text to speech program directly from BASIC 
via a USR call. From DOS type VS48 for a 48K system (and press 
ENTER) or VS32 for a 32K system This loads the text to speech 
program in high memory it protects itself (EDOOH to FFFFH for 
48K, ADOOH to BFFFH for 32K, 6DOOH to 7FFFH for 16K tape 
systems). You don't need any pokes as with PRINT*. Instead a 
DEFUSR is required:

DEFUSRO=&HEDOO or DEFUSRO=-4864 for a 48K system

DEFUSRO=&HADOO or DEFUSRO=-21248 for a 32K system

NOTE: It doesn't have to be USRO. In the examples below, "USR" 
is used instead of "USR0", as they are identical. Once the USR 
is defined as above, a simple USR call, such as B$=USR("any 
string") will produce speech.

Here is an example:

10 DEFUSRO=&HEDOO `for 48K. Use DEFUSR=&HADOO for 32K.
20 CLS: CLEAR 500 `clear some space for input string 
30 LINE INPUT"Type something!";A$ 
40 B$=USR(A$) ` speaks it 
50 GOTO 30 

When line 50 is executed, the content of A$ is spoken; A$ 
remains unchanged. (B$ contains the list of the phoneme codes 
just spoken. Each byte is the ASCII character for the phoneme 
codes 64 to 127). In the direct mode, a speech command could 
be: B$=USR("Good morning")

*METHOD 3: VSEDIT/BAS (disk) or V (tape)

* VSEDIT/BAS is a BASIC program that allows you to create short 
message subroutines which can be merged later with your 
existing programs. The advantage of this method is that once 
you have created the subroutines, you do not need to keep the 
VS text to speech program in high memory. You can also "fine 
tune" the messages by editing the phonemes or trying different 
spellings.

* Each subroutine is one line long and self contained. Once the 
message is developed, you only need that single line to speak 
it. The line ends with a RETURN, so you just use a GOSUB. The 
limitation is that you must have all the messages pre-planned. 
Let's see it in action. If it's not yet done, from DOS: type 
VS48 for 48K systems (and press ENTER) or V532 for 32K systems 
then enter BASIC and type RUN"VSEDIT/BAS". You will see a menu 
on the bottom of the screen with the following commands:

* I - Insert words. This is similar to the VSDEMO/BAS program. 
Simply type the words you want to hear and press ENTER; they 
will be spoken. In addition, the phonemes will appear at the 
top of the screen. Each one is preceeded by a graphic dot 
representing the pitch. (We will explain that later).

* By pressing "I" again, you can insert new words. Press ENTER, 
and the addition will be spoken and the new phonemes will be 
displayed.

* <ENTER> - Say all. Each time you press <ENTER>, the whole 
text will be spoken.

* S - Say one word. The word under the cursor is pronounced.

* ARROW KEYS - Move cursor. The four arrow keys let you move 
the cursor in the four directions.

* SHIFT LEFT or SHIFT RIGHT ARROWS - Move cursor back or forth 
one word at a time. To say all the text one word at a time, 
move the cursor to the top left, then use S and SHIFT RIGHT 
ARROW alternately.

* R - Remove word. The word under the cursor is deleted.

* K - Clear all. You will be asked if you really want to clear 
the whole text (as a safety precaution). Type Y if you want to, 
N if you don't. Remember to type I to enter new text.

* A - Add phoneme. The program will ask you for a valid Votrax 
phoneme. (See chart). Then you are asked for a pitch level. We 
will explain that later; for now simply press ENTER.

* D - Delete. The phoneme under the cursor is deleted.

* C - Change. The phoneme is deleted and you are asked to put a 
new one in its place as in the "A" (Add phoneme) command.

* Now is the time to discuss pitch control. The VS-100 is 
capable of saying phonemes at one of four pitch levels. The 
pitch is the frequency of the sound. For example, a man's voice 
has a lower pitch than a woman's. To the base pitch are added 
very small variations, called inflections. Your VS-100 will 
automatically add these inflections, making the speech sound 
more natural.

* SHIFT UP or SHIFT DOWN ARROW - controls the base pitch. (Note 
that SHIFT DOWN ARROW will not work on the Model III and on 
some Model I's). Let's work with an example

- Type K to clear the screen,

- Y to proceed, and I to insert text. Type "Hello hello" and 
hit ENTER. You will hear the VS-100 say hello twice, and the 
screen will show twice the four phonemes required, followed by 
the pause code PAO. You will also notice the graphic dot in 
front of each phoneme. This dot is a representation of one of 
the four pitch levels we can choose.

- With the left arrow key, move the cursor to the first "H" 
phoneme. Now hit shift up arrow four times. You will see the 
graphic representation of the four levels.

Level 1: no dot   Level 2:     Level 3: *     Level 4: *
(lowest)                   *                 (highest) *

The VS-100 automatically sets the phonemes at level 2.

- Use the shift up arrow to manually change the 4 phonemes of 
the first `*Hello** to the highest pitch. Then press ENTER to 
hear the result of the change. Now you are ready to try out 
different variations of pitches.

- * - Save message. This is a powerful function, so we'll 
explain it in detail. The VSEDIT program allows you to save on 
disk as many coded messages as vou want, each one up to 15 
seconds long. The purpose of the "Save message" command is to 
create a single line of BASIC code. This line, when executed 
will speak your message WITHOUT the help of the VS32 or VS48 
text to speech programs. All the phonemes codes and the BASIC 
commands needed to say them are stored within the BASIC line. 
The line ends with a "RETURN", so it becomes a simple 
subroutine. Example of line created by VSEDIT "*" command: 

20000 OUT236,16:FORVS%=1TO6:OUT11,ASC(MIDS("XFC",VS%)): 
NEXTVS%:RETURN

*NOTE 1: OUT236,16 is needed only on the model III to enable 
the input/output bus. It has no effect on the model I.

**NOTE 2: "XFC" is the ASCII representation of the phoneme code 
list.

* The line is created by VSEDIT, which saves the line to disk 
as an ASCII file. This file can later be added to your program 
with the "MERGE" command. Simply make certain that your program 
lines don't conflict with the new ones created by VSEDIT. Let's 
use an actual example:

We want to use a large number of pre-set warning or welcome 
messages. Each one will be created by the following sequence:

* Type your message and fine tune it.

* Type *. (Use shift key)

* The computer will ask you for the disk file name.

* Answer with any valid disk file that you AREN'T using yet.  
Let's use VOICE/TXT (TXT is the standard extension for ASCII 
files). You can of course specify any drive number as well i.e. 
VOICE/TXT:l.

* Press enter, then you are asked for a line number.

* Pick a line number that isn't used in your program.

* When you press enter, VSEDIT will take a few seconds to 
create the BASIC line, then it will save it to the disk file 
you chose.

* After saving the file, VSEDIT asks if you want to clear the 
phonemes. Answer "Y" or "N". You then return to the menu.


* You can create many messages and save them in the same manner.

*NOTE 1: Except for TRSDOS on the model I, you can save more 
than one subroutine in each file. (Be sure to use different 
line numbers). If you are using TRSDOS on the Model I, use 
different file names for each message.

**NOTE 2: If you are using NEWDOS/80 Version 2.0, then the line 
numbers must be in ascending order. NEWDOS doesn't order the 
lines when you MERGE, other DOSes do.

***NOTE 3: It's a good idea to keep track of the messages and 
corresponding line numbers that you use. It will make it easier 
to add them to your programs later.

**NOTE 4: NEWDOS+ 2.1 users: you will have to disable the 
automatic conversion of lower case to upper case if you want to 
use pitch 2. IMPORTANT: There are some limitations involved in 
saving messages with various pitches. Refer to the "Pitch 
Control" section of this manual if you want to use pitches 
other than the default pitch.

* ? - Recall from disk.  This lets you get one of the messages 
that you saved to disk so that you can change it. You are asked 
for the file name. Type it in and press <enter>. The file must 
be an ASCII (text) file for VSEDIT to work. You will then be 
asked for the line number. Type the line corresponding to the 
message you want to edit and press <enter>. NOTE : When you 
save the changed message, note that VSEDIT will add the new 
line to the end of the existing file. It will not overwrite the 
previous line with that number until it is LOADed into BASIC 
(NEWDOS/80 version 2.0 will not work if the lines aren't in 
order).

*METHOD 4: Phoneme direct output from BASIC

* This method is described for reference only. Considering the 
convenience of the methods 1,2 and 3, we don't see any reason 
to use it.

* You can use the phoneme table (later in this manual) to 
create words by looking up the proper codes for each sound in 
the word. For example, let's say you want to add the word 
"daddy". The first sound is "d" which is code number 30. The 
"a" sounds like the "a" in "dad" (on the table) therefore, the 
phoneme is "AE" which is number 46. If you keep doing this you 
will get all the phonemes for the "daddy": D,AE,D,D,E or codes 
30,46,30,30,44. Model I

* To get speech, you must output each code to the VS-100. Use 
the OUT 11,X statement, where "X" is the code number. In our 
case, the following line will say "daddy": 

10 OUT11,30 : OUT11,46 : OUT11,30 :OUT11,30 : OUT11,44 

Note: This is a simple example. Generally you will use DATA 
statements and FOR ... NEXT loops to output the codes.

* The VS-100 for the Model III sends a "busy" signal back of 
the computer while the VS is talking. The software must look at 
this "status bit" before it sends the next phoneme. Bit 7 of 
port 11 is low while the VS is busy. If you really want to use 
this method, you must use a short subroutine which checks the 
status bit prior to sanding each phoneme code. Ex:

100 IF INP(11)>127 THEN RETURN ELSE 100

Also remember that you have to enable the Model 111 1/0 bus by 
with an OUT 236,16. Our "Daddy" line above would be:

10 OUT 236,16 : GOSUB 100 : OUT 11,30 : GOSUB 100 : OUT 11,46 : 
GOSUB 100 : OUT 11,30 : GOSUB 100 : OUT 11,30 : GOSUB 100 : OUT 
11,44

Pitch control

* This paragraph is a bit technical, but it should be 
understandable.

* The computer communicates with the VS-100 via an eight bit 
byte. The VS-100 Votrax chip uses the lower six bits to select 
one of the sixty four phonemes. The remaining two bits are used 
to select a base pitch. Two bits give us four possibilities, so 
there are four base pitches. The four pitches are numbered 1 to 
4. Phonemes with the lowest pitch use numbers 0 to 63. Phonemes 
with pitch 2 use the numbers 64 to 127, phonemes with pitch 3 
use numbers 128 to 191, and phonemes with pitch 4 use numbers 
192 to 255. Note that phoneme codes 0,64,128 and 192 are the 
same sound, only at different pitches. To select pitch 2,3 or 
4, add 64, 128 or 192 to the phoneme code in the table.

* If you are using VSEDIT, keep in mind the following: If you 
save messages with pitch 2 (the default), you will get ASCII 
codes 64-127 embedded in the message line. These codes are a 
mixture of upper and lower case and some other characters. They 
will not affect your listing in any way. If you use pitches 3 
or 4, you will see that your line is filled with keywords 
FORPRINTCHR$(INKEY$ ) because codes above 127 are "tokens" for 
BASIC keywords. The line will run correctly, however it will 
look odd in listings. (There might be a problem if the line 
gets longer than 255 characters on the screen.  Everything will 
work fine unless you try to EDIT the line or if you try to save 
it in a ASCII file).

* If you use pitch 1, the program line will contain ASCII 
control characters, such as "clear screen" and "form feed". 
This line will execute properly, but it will produce strange 
effects on the screen, during listings. This is because the 
control characters are executed when that line is listed. 
Again, this has no effect on the execution of the program. The 
same applies to LLIST, for the printer may skip a page if 
it receives a "form feed" code.

* Also, pitch 1 phoneme codes 0, 13 and 34 are automatically 
replaced with codes 1, 77, and 41. The former codes (which 
correspond to null, CR, and ") cannot be embedded in the BASIC 
line, so they are converted by VSEDIT to the closest equivalent 
phoneme.

Machine Language Programming

This section is only for machine language programmers.  To add 
VS48 or VS32 with machine language software, you must do the 
following:

* Create a three byte pointer to a string containing the words 
to be spoken.  (first byte is the length; second and third 
bytes are the string location.

* Store the location of this pointer in 4121H.

* CALL 0ED00H for VS48 or 0AD00H for VS32

* The VS-100 will speak and the phomeme codes will be stored in 
a string.  The location of the pointer to this string will be 
in 4121H.

Example:  You want the computer to say: "Good morning".  The 
string "Good morning" is stored at 8000H - 800BH.  Your pointer 
would be 0C,00,80.  Let's say you stored this pointer at 7F00H.  
Store 7F00H in 4121H and user the command

CALL 0ED00H ; for VS48, or
CALL 0AD00H ; for VS32

That's all that you have to do.  All registers are saved and restored.

Phoneme list:

Ph.     Code    As in           Duration
========================================
A       32      dAY             185
A1      6       mAde            103
A2      5       enAble          71
AE      46      dAd             185
AE1     47      After           103
AH      36      mOp             250
AH1     21      fAther          146
AH2     8       hOnest          71
AW      61      cAll            250
AW1     19      lAWful          146
AW2     48      sAlty           90
AY      33      jAde            65
B       14      Bag             71
CH*     16      CHip            71
D       30      paiD            55
DT      4       buTTer          46
E       44      mEEt            185
E1      60      bE              121
EH      59      gEt             185
EH1     2       hEAvy           121
EH2     1       Enlist          71
EH3     0       jackEt          59
ER      58      bIrd            146
F       29      Fast            103
G       28      Get             71
H       27      Hello           71
I       39      pIn             185
I1      11      inhibIt         121
I2      10      Inhibit         80
I3      9       inhIbit         55
IU      54      yOU             59
J*      26      JuDGe           47
K       25      triCK           80
L       24      Land            103
M       12      Mat             103
N       13      suN             80
NG      20      thiNG           121
O       38      cOld            185
O1      53      abOArd          121
O2      52      fOr             80
OO      23      bOOk            185
OO1     22      lOOking         103
P       37      Past            103
PA0     3       no sound        47
PA1     62      no sound        185
R       43      Red             90
S       31      paSS            90
SH      17      SHop            121
STP     63      no sound        47
T       42      Tap             71
TH      57      THin            71
THV     56      THe             80
U       40      mOve            185
U1      55      jUne            90
UH      51      cUp             185
UH1     50      UNcle           103
UH2     49      About           71
UH3     35      missIOn         47
V       15      Van             71
W       45      Win             80
Y       41      anY             103
Y1      34      Yard            80
Z       18      Zoo             71
ZH      7       pleaSUre        90

Codes are for pitch 1.  For pitch 2,3 or 4 add 64,128 or 192 
Capital letters represent the sound produced.

* To produce the "CH" sound, T must precede CH.
  To produce the "J" sound, D must precede J.

Note 1: The numbers in the phonemes (Ex: UH2) have no effect on 
the sound they only affect the duration.  Higher numbers mean 
shorter sounds.

Note 2: The phoneme duration is indicated in milliseconds. 
They are shown for comparison purposes only.
